OLA 文档中心

主题

2026-08-20

日志模块总览 - Overview ​

本分类做什么 ​

可配置文件日志：路径、格式、级别、轮转、颜色、异步、多实例；控制台 与 OpenConsole/CloseConsole 联动；以及 全局自定义 Skin（回调输出，按 logger 勾选）。

写日志接口分 Trace～Critical 及 Ex 变体（附加字段见各页）。

一、生命周期与全局配置 ​

接口差异
LogShutdown全局 关闭。
LogCreateInstance、LogDestroyInstance多实例 日志器（多模块分文件）。
LogSetFilePath、LogSetPattern、LogSetLevel、LogGetLevel文件、格式模式、级别。
LogSetTarget输出到 文件 / 控制台 / 用户 Skin（可组合）。
LogSetAsync、LogSetFlushInterval异步 与 刷盘间隔。

二、自定义日志 Skin（全局回调） ​

Skin 全局注册，返回位枚举；再对某个 logger 调用 LogSetTarget 勾选。

接口说明
OLALogSkinCallback回调类型：level + raw + formatted + userData。
LogRegisterSkin全局注册，返回 Skin 位枚举（最多 24 个）。
LogUnregisterSkin按位枚举注销。
LogClearSkins清空全部全局 Skin。

推荐顺序：RegisterSkin → SetTarget(logger, FILE \| skin) → 写日志。

差异：Skin 与 logger 解耦——一次注册，多个 logger 可共用或分别选用不同 Skin。

三、文件与目录策略 ​

接口用途
LogSetMaxFileSize、LogSetMaxFiles单文件上限 与 保留个数（轮转）。
LogSetBaseDirectory、LogSetDirMode、LogSetFileNamePattern目录结构 与 文件名模式。
LogSetRotationMode、LogSetAppendMode切分策略、追加/覆盖。
LogRotateFile、LogCleanupOldFiles手动切分、清理历史。

差异：Pattern 决定 行格式；DirMode 决定 按日期/模块分子目录（见详情页）。

四、控制台与颜色 ​

接口说明
OpenConsole、CloseConsole本机 / 当前绑定窗口控制台。
OpenConsoleEx、CloseConsoleEx按 hwnd。
LogSetColorMode、LogSetLevelColor、LogResetLevelColors控制台颜色 与 级别着色。

五、写入接口：普通 vs Ex ​

级别普通Ex
Trace～CriticalLogTrace … LogCriticalLogTraceEx … LogCriticalEx

差异：Ex 可指定 loggerHandle（多实例）；普通接口操作默认实例。

六、查询 ​

接口用途
LogGetCurrentFilePath、LogGetCurrentFileSize、LogGetTotalFilesCount当前文件与 历史文件数。

七、快速选型 ​

需求建议
多 DLL 分日志LogCreateInstance
按天切分LogSetRotationMode + LogSetFileNamePattern
高性能LogSetAsync + 合理 FlushInterval
UI / 自研输出LogRegisterSkin + LogSetTarget(..., skin)
两路不同回调注册两个 Skin，两个 logger 分别 SetTarget
编码写日志输入走 DefaultEncoding；Skin 回调字符串走 DefaultReturnEncoding

八、推荐调用链（示例导向） ​

各接口详情页已补全联动 demo，可按场景直接抄：

默认实例最小可用

LogSetLevel(0, 2) → LogSetTarget(0, 1|2) → OpenConsole(0)
        → LogInfo("...") → LogFlush(0)

按天 / 按大小滚动文件

LogSetBaseDirectory → LogSetModuleName → LogSetFileNamePattern("{module}_{date}_{index}.log")
        → LogSetDirMode(DATE|MODULE) → LogSetRotationMode(SIZE|DAILY)
        → LogSetMaxFileSize / LogSetMaxFiles → 写日志 → LogGetCurrentFilePath

多实例分文件

h = LogCreateInstance("NetworkLogger") → 对该 h 做配置
        → LogInfoEx(h, "...") → LogFlush(h) → LogDestroyInstance(h)

自定义 Skin 输出

skin = LogRegisterSkin(cb, 0) → LogSetAsync(h, 0) → LogSetTarget(h, FILE|skin)
        → LogInfoEx(h, "...") → LogFlush(h) → LogUnregisterSkin(skin)

普通写接口（LogInfo 等）只写默认实例；指定实例请用 Log*Ex。

九、注意 ​

  • 多线程 写日志是否完全无锁以版本为准。
  • 敏感数据 勿打明文密码。
  • Skin 回调 进程内有效；须 OLA_CALL_TYPE（stdcall）；异步模式下可能在线程池触发，勿对同一 logger 重入配置/写日志。
  • 级别过滤 后的日志不会触发 Skin 回调。